/**
 * This file is part of 1genia trampoline
 * Copyright (C) 2007-2008 1genia (contact@1genia.com)
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; version 3 of the License. 
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details. 
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; see the file COPYING.TXT.  If not,
 * write to the Free Software Foundation, Inc., 51 Franklin Street,
 * Fifth Floor, Boston, MA 02110-1301, USA. 
 **/
package com.genia.toolbox.projects.toolbox_basics_project.business.dao;

import java.util.List;

import com.genia.toolbox.basics.exception.technical.TechnicalException;
import com.genia.toolbox.persistence.exception.PersistenceException;
import com.genia.toolbox.projects.toolbox_basics_project.bean.model.Template;
import com.genia.toolbox.projects.toolbox_basics_project.bean.model.TemplateType;

/**
 * DAO to access {@link Template} and {@link TemplateType}.
 */
public interface TemplateDAO
{

  /**
   * the reference name of the root template.
   */
  public static final String ROOT_TEMPLATE_REFERENCE_NAME = "root";



  /**
   * returns the {@link TemplateType} associated to the given reference name.
   * 
   * @param referenceName
   *          the reference name of the {@link TemplateType}
   * @return the {@link TemplateType} associated to the given reference name, if
   *         no such {@link TemplateType} exists prior to the call of this
   *         function, on such {@link TemplateType} will be created
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract TemplateType getOrCreateTemplateType(String referenceName)
      throws TechnicalException;



  /**
   * returns the {@link TemplateType} associated to the given reference name.
   * 
   * @param referenceName
   *          the reference name of the {@link TemplateType}
   * @return the {@link TemplateType} associated to the given reference name or
   *         <code>null</code> if no such {@link TemplateType} exists prior to
   *         the call of this function
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract TemplateType getTemplateType(String referenceName)
      throws TechnicalException;



  /**
   * returns the {@link Template} associated to the given reference name.
   * 
   * @param templateType
   *          the type of the {@link Template} to retrieve
   * @param referenceName
   *          the reference name of the {@link Template}, if this value is
   *          <code>null</code>, the root {@link Template} will be returned
   * @return the {@link Template} associated to the given reference name, if no
   *         such {@link Template} exists prior to the call of this function, on
   *         such {@link Template} will be created
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract Template getOrCreateTemplate(TemplateType templateType, String referenceName)
      throws TechnicalException;



  /**
   * returns the {@link Template} associated to the given reference name.
   * 
   * @param templateType
   *          the type of the {@link Template} to retrieve
   * @param referenceName
   *          the reference name of the {@link Template}, if this value is
   *          <code>null</code>, the root {@link Template} will be returned
   * @return the {@link Template} associated to the given reference name or
   *         <code>null</code> if no such {@link Template} exists prior to the
   *         call of this function
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract Template getTemplate(TemplateType templateType, String referenceName)
      throws TechnicalException;



  /**
   * update a {@link Template}.
   * 
   * @param template
   *          the {@link Template} to save
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract void updateTemplate(Template template)
      throws TechnicalException;



  /**
   * returns the {@link List} of {@link Template} having the given
   * {@link TemplateType}.
   * 
   * @param templateType
   *          the {@link TemplateType} of the templates to return
   * @return the {@link List} of {@link Template} having the given
   *         {@link TemplateType}
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract List<Template> getTemplates(TemplateType templateType)
      throws TechnicalException;



  /**
   * return a {@link List} of {@link Template} having the given
   * {@link TemplateType} and the name.
   * 
   * @param templateType
   *          the {@link TemplateType} of the templates to return
   * @param name
   *          the name of the {@link Template}, if this value is
   *          <code>null</code>, it returns all {@link Template} having given
   *          the {@link TemplateType}
   * @return a {@link List} of {@link Template} having the given
   *         {@link TemplateType} and the name
   * @throws PersistenceException
   *           if an error occured
   * @see com.genia.toolbox.projects.toolbox_basics_project.business.dao.TemplateDAO#findTemplates(com.genia.toolbox.projects.toolbox_basics_project.bean.model.TemplateType,
   *      java.lang.String)
   */
  public List<Template> findTemplates(TemplateType templateType, String name)
      throws PersistenceException;



  /**
   * return all {@link TemplateType}.
   * 
   * @return all {@link TemplateType}
   * @throws PersistenceException
   *           if an error occured
   */
  public abstract List<TemplateType> getAllTemplateTypes()
      throws PersistenceException;



  /**
   * get the {@link TemplateType} by its identifier.
   * 
   * @param identifier
   *          the {@link TemplateType} identifier
   * @return the {@link TemplateType}
   * @throws PersistenceException
   *           when error occured.
   */
  public abstract TemplateType getTemplateType(Long identifier)
      throws PersistenceException;



  /**
   * get the {@link Template} by its identifier.
   * 
   * @param identifier
   *          the {@link Template} identifier
   * @return the {@link Template}
   * @throws PersistenceException
   *           when error occured.
   */
  public abstract Template getTemplate(Long identifier)
      throws PersistenceException;



  /**
   * delete a {@link Template}.
   * 
   * @param template
   *          the {@link Template} to delete.
   * @throws PersistenceException
   *           when error occured.
   * @see com.genia.toolbox.projects.toolbox_basics_project.business.dao.TemplateDAO#deleteTemplates()
   */
  public abstract void deleteTemplate(Template template)
      throws PersistenceException;
}
